MV_CC_GetImageBuffer

MV_CC_GetImageBuffer

Get one frame of picture, support getting chunk information and setting timeout.

API Definition

int MV_CC_GetImageBuffer(
  void                  *handle,
  MV_FRAME_OUT          *pFrame,
  int                   nMsec
);

Parameters

handle

[IN] Device handle, which is returned by MV_CC_CreateHandle or MV_CC_CreateHandleWithoutLog.

pFrame

[OUT] Image data and information, see the structure MV_FRAME_OUT for details.

nMsec

[IN] Timeout duration, unit: millisecond

Return Value

Return MV_OK(0) on success, and return Error Code on failure.

Remarks

  • Before calling this API to get image data frame, you should call MV_CC_StartGrabbing to start image acquisition. This API can get frame data actively, the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, and SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.

  • This API and MV_CC_FreeImageBuffer should be called in pairs, after processing the acquired data, you should call MV_CC_FreeImageBuffer to release the data pointer permission of pFrame.

  • This API whose streaming buffer is allocated by the SDK automatically, has higher image acquisition efficiency than MV_CC_GetOneFrameTimeout (). Interface A is more efficient than interface B, because the cache of interface A is automatically allocated by the SDK, and interface B is manually allocated by the user

  • This API cannot be called to stream after calling MV_CC_DisplayOneFrame.

  • This API is not supported by CameraLink device.

  • This API is supported by both USB3 vision camera and GigE camera.

The following sample code is for reference only.

#include "MvCameraControl.h"

void main()
{
    int nRet = -1;
    void* m_handle = NULL;

    //Enumerate all devices corresponding to specified transport protocol within subnet
     unsigned int nTLayerType = MV_GIGE_DEVICE | MV_USB_DEVICE;
    MV_CC_DEVICE_INFO_LIST m_stDevList = {0};
    int nRet = MV_CC_EnumDevices(nTLayerType, &m_stDevList);
    if (MV_OK != nRet)
    {
        printf("error: EnumDevices fail [%x]\n", nRet);
        return;
    }

    int i = 0;
    if (m_stDevList.nDeviceNum == 0)
    {
        printf("no camera found!\n");
        return;
    }

    //Select the first found online device and create device handle
    int nDeviceIndex = 0;

    MV_CC_DEVICE_INFO m_stDevInfo = {0};
    memcpy(&m_stDevInfo, m_stDevList.pDeviceInfo[nDeviceIndex], sizeof(MV_CC_DEVICE_INFO));

    nRet = MV_CC_CreateHandle(&m_handle, &m_stDevInfo);

    if (MV_OK != nRet)
    {
        printf("error: CreateHandle fail [%x]\n", nRet);
        return;
    }

    //Connect to device
     nRet = MV_CC_OpenDevice(m_handle, nAccessMode, nSwitchoverKey);
    if (MV_OK != nRet)
    {
        printf("error: OpenDevice fail [%x]\n", nRet);
        return;
    }
    //...other processing

     //Start acquiring images
     nRet = MV_CC_StartGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StartGrabbing fail [%x]\n", nRet);
        return;
    }

    MV_FRAME_OUT stOutFrame;
    memset(&stOutFrame, 0, sizeof(MV_FRAME_OUT));

    //The upper layer should control the frequency of calling this API according to frame rate.
     //The codes are for reference only, it is recommended to create a new thread for image acquisition and processing
     while(1)
    {
        if (nTestFrameSize > 99) 
        {
            break;
        }
        nRet = MV_CC_GetImageBuffer(m_handle, &stOutFrame, 1000);
        if (MV_OK != nRet)
        {
            Sleep(10);
        }
        else
        {
            //...Process image data
            nTestFrameSize++;
        }
        nRet = MV_CC_FreeImageBuffer(m_handle, &stOutFrame);
        if(nRet != MV_OK)        {            printf("Free Image Buffer fail! nRet [0x%x]\n", nRet);
        }
    }

    //...other processing

     //Stop image acquisition
     nRet = MV_CC_StopGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StopGrabbing fail [%x]\n", nRet);
        return;
    }

    //Close device, and release resource
     nRet = MV_CC_CloseDevice(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: CloseDevice fail [%x]\n", nRet);
        return;
    }

    //Destroy handle and release resource
     nRet = MV_CC_DestroyHandle(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: DestroyHandle fail [%x]\n", nRet);
        return;
    }    
}

MV_CC_GetImageBuffer

Get one frame of picture, support getting chunk information and setting timeout.

API Definition

int MV_CC_GetImageBuffer(
  void                  *handle,
  MV_FRAME_OUT          *pFrame,
  int                   nMsec
);

Parameters

handle

[IN] Device handle, which is returned by MV_CC_CreateHandle or MV_CC_CreateHandleWithoutLog.

pFrame

[OUT] Image data and information, see the structure MV_FRAME_OUT for details.

nMsec

[IN] Timeout duration, unit: millisecond

Return Value

Return MV_OK(0) on success, and return Error Code on failure.

Remarks

  • Before calling this API to get image data frame, you should call MV_CC_StartGrabbing to start image acquisition. This API can get frame data actively, the upper layer program should control the frequency of calling this API according to the frame rate. This API supports setting timeout, and SDK will wait to return until data appears. This function will increase the streaming stability, which can be used in the situation with high stability requirement.

  • This API and MV_CC_FreeImageBuffer should be called in pairs, after processing the acquired data, you should call MV_CC_FreeImageBuffer to release the data pointer permission of pFrame.

  • This API whose streaming buffer is allocated by the SDK automatically, has higher image acquisition efficiency than MV_CC_GetOneFrameTimeout (). Interface A is more efficient than interface B, because the cache of interface A is automatically allocated by the SDK, and interface B is manually allocated by the user

  • This API cannot be called to stream after calling MV_CC_DisplayOneFrame.

  • This API is not supported by CameraLink device.

  • This API is supported by both USB3 vision camera and GigE camera.

The following sample code is for reference only.

#include "MvCameraControl.h"

void main()
{
    int nRet = -1;
    void* m_handle = NULL;

    //Enumerate all devices corresponding to specified transport protocol within subnet
     unsigned int nTLayerType = MV_GIGE_DEVICE | MV_USB_DEVICE;
    MV_CC_DEVICE_INFO_LIST m_stDevList = {0};
    int nRet = MV_CC_EnumDevices(nTLayerType, &m_stDevList);
    if (MV_OK != nRet)
    {
        printf("error: EnumDevices fail [%x]\n", nRet);
        return;
    }

    int i = 0;
    if (m_stDevList.nDeviceNum == 0)
    {
        printf("no camera found!\n");
        return;
    }

    //Select the first found online device and create device handle
    int nDeviceIndex = 0;

    MV_CC_DEVICE_INFO m_stDevInfo = {0};
    memcpy(&m_stDevInfo, m_stDevList.pDeviceInfo[nDeviceIndex], sizeof(MV_CC_DEVICE_INFO));

    nRet = MV_CC_CreateHandle(&m_handle, &m_stDevInfo);

    if (MV_OK != nRet)
    {
        printf("error: CreateHandle fail [%x]\n", nRet);
        return;
    }

    //Connect to device
     nRet = MV_CC_OpenDevice(m_handle, nAccessMode, nSwitchoverKey);
    if (MV_OK != nRet)
    {
        printf("error: OpenDevice fail [%x]\n", nRet);
        return;
    }
    //...other processing

     //Start acquiring images
     nRet = MV_CC_StartGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StartGrabbing fail [%x]\n", nRet);
        return;
    }

    MV_FRAME_OUT stOutFrame;
    memset(&stOutFrame, 0, sizeof(MV_FRAME_OUT));

    //The upper layer should control the frequency of calling this API according to frame rate.
     //The codes are for reference only, it is recommended to create a new thread for image acquisition and processing
     while(1)
    {
        if (nTestFrameSize > 99) 
        {
            break;
        }
        nRet = MV_CC_GetImageBuffer(m_handle, &stOutFrame, 1000);
        if (MV_OK != nRet)
        {
            Sleep(10);
        }
        else
        {
            //...Process image data
            nTestFrameSize++;
        }
        nRet = MV_CC_FreeImageBuffer(m_handle, &stOutFrame);
        if(nRet != MV_OK)        {            printf("Free Image Buffer fail! nRet [0x%x]\n", nRet);
        }
    }

    //...other processing

     //Stop image acquisition
     nRet = MV_CC_StopGrabbing(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: StopGrabbing fail [%x]\n", nRet);
        return;
    }

    //Close device, and release resource
     nRet = MV_CC_CloseDevice(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: CloseDevice fail [%x]\n", nRet);
        return;
    }

    //Destroy handle and release resource
     nRet = MV_CC_DestroyHandle(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: DestroyHandle fail [%x]\n", nRet);
        return;
    }    
}